package com.zenithmind.mall.service;

import java.util.List;
import java.util.Map;

/**
 * 秒杀库存服务接口 - 遵循接口隔离原则，专门负责秒杀库存管理和防超卖
 * 
 * @author ZenithMind Team
 * @since 2025-07-03
 */
public interface SeckillStockService {

    /**
     * 检查秒杀商品库存
     * 
     * @param seckillProductId 秒杀商品ID
     * @param quantity 需要的数量
     * @return 库存是否充足
     */
    Boolean checkSeckillStock(String seckillProductId, Integer quantity);

    /**
     * 扣减秒杀库存（使用Redis分布式锁防超卖）
     * 
     * @param seckillProductId 秒杀商品ID
     * @param quantity 扣减数量
     * @return 是否成功
     */
    Boolean decreaseSeckillStock(String seckillProductId, Integer quantity);

    /**
     * 恢复秒杀库存（取消订单时）
     * 
     * @param seckillProductId 秒杀商品ID
     * @param quantity 恢复数量
     * @return 是否成功
     */
    Boolean restoreSeckillStock(String seckillProductId, Integer quantity);

    /**
     * 预扣库存（下单时临时扣减）
     * 
     * @param seckillProductId 秒杀商品ID
     * @param quantity 预扣数量
     * @param userId 用户ID
     * @return 预扣令牌
     */
    String preDeductStock(String seckillProductId, Integer quantity, String userId);

    /**
     * 确认扣库存（支付成功后确认扣减）
     * 
     * @param token 预扣令牌
     * @return 是否成功
     */
    Boolean confirmDeductStock(String token);

    /**
     * 取消预扣库存（支付失败或超时）
     * 
     * @param token 预扣令牌
     * @return 是否成功
     */
    Boolean cancelPreDeductStock(String token);

    /**
     * 获取秒杀商品剩余库存
     * 
     * @param seckillProductId 秒杀商品ID
     * @return 剩余库存数量
     */
    Integer getSeckillRemainingStock(String seckillProductId);

    /**
     * 获取秒杀商品已售数量
     * 
     * @param seckillProductId 秒杀商品ID
     * @return 已售数量
     */
    Integer getSeckillSoldCount(String seckillProductId);

    /**
     * 初始化秒杀库存到Redis
     * 
     * @param seckillProductId 秒杀商品ID
     * @param stock 库存数量
     * @return 是否成功
     */
    Boolean initSeckillStock(String seckillProductId, Integer stock);

    /**
     * 批量初始化秒杀库存
     * 
     * @param stockMap 库存映射（秒杀商品ID -> 库存数量）
     * @return 是否成功
     */
    Boolean batchInitSeckillStock(Map<String, Integer> stockMap);

    /**
     * 同步秒杀库存到数据库
     * 
     * @param seckillProductId 秒杀商品ID
     * @return 是否成功
     */
    Boolean syncSeckillStockToDb(String seckillProductId);

    /**
     * 批量同步秒杀库存到数据库
     * 
     * @param seckillProductIds 秒杀商品ID列表
     * @return 同步结果
     */
    Boolean batchSyncSeckillStockToDb(List<String> seckillProductIds);

    /**
     * 清理过期的预扣库存
     * 
     * @return 清理数量
     */
    Integer cleanExpiredPreDeductStock();

    /**
     * 获取秒杀商品库存进度
     * 
     * @param seckillProductId 秒杀商品ID
     * @return 库存进度百分比
     */
    Double getSeckillStockProgress(String seckillProductId);

    /**
     * 检查秒杀商品是否售罄
     * 
     * @param seckillProductId 秒杀商品ID
     * @return 是否售罄
     */
    Boolean isSeckillSoldOut(String seckillProductId);

    /**
     * 设置秒杀商品售罄状态
     * 
     * @param seckillProductId 秒杀商品ID
     * @return 是否成功
     */
    Boolean setSeckillSoldOut(String seckillProductId);

    /**
     * 获取用户秒杀购买记录
     * 
     * @param seckillProductId 秒杀商品ID
     * @param userId 用户ID
     * @return 购买数量
     */
    Integer getUserSeckillBuyCount(String seckillProductId, String userId);

    /**
     * 记录用户秒杀购买
     * 
     * @param seckillProductId 秒杀商品ID
     * @param userId 用户ID
     * @param quantity 购买数量
     * @return 是否成功
     */
    Boolean recordUserSeckillBuy(String seckillProductId, String userId, Integer quantity);

    /**
     * 检查用户是否超过限购数量
     * 
     * @param seckillProductId 秒杀商品ID
     * @param userId 用户ID
     * @param quantity 本次购买数量
     * @return 是否超过限购
     */
    Boolean isExceedUserLimit(String seckillProductId, String userId, Integer quantity);
}
